cliui

What is cliui?

The cliui npm package is a library for creating complex command-line interfaces with various layout controls such as word-wrapping, alignment, padding, and more. It allows developers to build structured and formatted output for command-line applications.

What are cliui's main functionalities?

Text alignment and wrapping

This feature allows for aligning text within a specified width and automatically wraps text that exceeds the width. Padding can be added around the text.

const cliui = require('cliui')({ width: 80 });

cliui.div(
  { text: 'Some long text that needs to be wrapped', align: 'left', padding: [1, 2, 1, 2] },
  { text: 'Aligned right', align: 'right' }
);

console.log(cliui.toString());

Column-based layout

This feature allows developers to create a layout based on columns, specifying the width of each column for structured output.

const cliui = require('cliui')({ width: 80 });

cliui.div(
  { text: 'Column 1', width: 30 },
  { text: 'Column 2', width: 30 },
  { text: 'Column 3', width: 20 }
);

console.log(cliui.toString());

Complex nested layouts

This feature supports creating nested layouts, allowing for complex and hierarchical interface designs.

const cliui = require('cliui')({ width: 80 });

cliui.div(
  {
    text: 'Top level',
    padding: [1, 0, 1, 0],
    border: true
  },
  {
    text: cliui.div(
      { text: 'Nested level 1', align: 'center' },
      { text: cliui.div(
        { text: 'Nested level 2', align: 'center' }
      )}
    )
  }
);

console.log(cliui.toString());

Other packages similar to cliui

chalk

Chalk is a popular npm package for styling terminal strings with colors and styles but does not provide layout controls like cliui.

boxen

Boxen allows you to create boxes in the terminal to highlight content. It is similar to cliui in that it helps format CLI output but does not offer the same level of layout control.

inquirer

Inquirer.js is a comprehensive library for creating interactive command-line user interfaces. It includes features for prompting users but is more focused on user input than output formatting like cliui.

blessed

Blessed is a high-level terminal interface library that is more complex and feature-rich than cliui, offering a full-fledged terminal interface API, including screen widgets and mouse events.

README

cliui

easily create complex multi-column command-line-interfaces.

Example

const ui = require('cliui')()

ui.div('Usage: $0 [command] [options]')

ui.div({
  text: 'Options:',
  padding: [2, 0, 1, 0]
})

ui.div(
  {
    text: "-f, --file",
    width: 20,
    padding: [0, 4, 0, 4]
  },
  {
    text: "the file to load." +
      chalk.green("(if this description is long it wraps).")
    ,
    width: 20
  },
  {
    text: chalk.red("[required]"),
    align: 'right'
  }
)

console.log(ui.toString())

Deno/ESM Support

As of v7 cliui supports Deno and ESM:

import cliui from "https://deno.land/x/cliui/deno.ts";

const ui = cliui({})

ui.div('Usage: $0 [command] [options]')

ui.div({
  text: 'Options:',
  padding: [2, 0, 1, 0]
})

ui.div({
  text: "-f, --file",
  width: 20,
  padding: [0, 4, 0, 4]
})

console.log(ui.toString())

Layout DSL

cliui exposes a simple layout DSL:

If you create a single ui.div, passing a string rather than an object:

• \n: characters will be interpreted as new rows.
• \t: characters will be interpreted as new columns.
• \s: characters will be interpreted as padding.

as an example...

var ui = require('./')({
  width: 60
})

ui.div(
  'Usage: node ./bin/foo.js\n' +
  '  <regex>\t  provide a regex\n' +
  '  <glob>\t  provide a glob\t [required]'
)

console.log(ui.toString())

will output:

Usage: node ./bin/foo.js
  <regex>  provide a regex
  <glob>   provide a glob          [required]

Methods

cliui = require('cliui')

cliui({width: integer})

Specify the maximum width of the UI being generated. If no width is provided, cliui will try to get the current window's width and use it, and if that doesn't work, width will be set to 80.

cliui({wrap: boolean})

Enable or disable the wrapping of text in a column.

cliui.div(column, column, column)

Create a row with any number of columns, a column can either be a string, or an object with the following options:

• text: some text to place in the column.
• width: the width of a column.
• align: alignment, right or center.
• padding: [top, right, bottom, left].
• border: should a border be placed around the div?

cliui.span(column, column, column)

Similar to div, except the next row will be appended without a new line being created.

cliui.resetOutput()

Resets the UI elements of the current cliui instance, maintaining the values set for width and wrap.

Changelog

7.0.4 (2020-11-08)

Bug Fixes

• deno: import UIOptions from definitions (#97) (f04f343)